---
title: Getting Started with v4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Introduction

DocSearch v4 provides a significant upgrade over previous versions, offering enhanced accessibility, responsiveness, and an improved search experience for your documentation. Built on [Algolia Autocomplete][1], DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.

## Installation

> Looking for the Composable API documentation? You can find it [here][17].

DocSearch packages are available on the [npm registry][10].

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```bash
yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4
```

### Without package manager

Include CSS in your website's `<head>`

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
```

</TabItem>
<TabItem value="react">

```bash
yarn add @docsearch/react@4
# or
npm install @docsearch/react@4
```

### Without package manager

Include CSS in your website's `<head>`:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>
```

</TabItem>

</Tabs>

### Optimize first query performance

Enhance your users' first search experience by using `preconnect`, see [Performance optimization](#preconnect) below

## Implementation

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

DocSearch requires a dedicated container in your HTML

```html
<div id="docsearch"></div>
```

Initialize DocSearch by passing your container:

```js app.js
import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});
```

DocSearch generates an accessible, fully-functional search input for you automatically.

</TabItem>

<TabItem value="react">

Integrating DocSearch into your React app is straightforward:

```jsx App.js
import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;
```

DocSearch generates a fully accessible search input out-of-the-box.

</TabItem>

</Tabs>

### Quick Testing (without credentials)

If you'd like to test DocSearch immediately without your own credentials, use our demo configuration:

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  askAi="askAIDemo"
/>
```

</TabItem>

</Tabs>

Or use our new dedicated [DocSearch Playground](https://community.algolia.com/docsearch-playground/)

### Using DocSearch with Ask AI

DocSearch v4 introduces support for Ask AI, Algolia's advanced, AI-powered search capability. Ask AI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation.

To enable Ask AI, you can add your Algolia Assistant ID as a string, or use an object for more advanced configuration (such as specifying a different index, credentials, or search parameters):

<Tabs groupId="askai-format" defaultValue="string" values={[{ label: 'String', value: 'string' }, { label: 'Object', value: 'object' }]}>
<TabItem value="string">

```js
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});
```

</TabItem>
<TabItem value="object">

```js
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    indexName: 'YOUR_MARKDOWN_INDEX', // Optional: use a different index for Ask AI
    apiKey: 'YOUR_SEARCH_API_KEY',     // Optional: use a different API key for Ask AI
    appId: 'YOUR_APP_ID',              // Optional: use a different App ID for Ask AI
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'], // Optional: filter Ask AI context
    },
    suggestedQuestions: true // Optional: enable loading suggested questions on the Ask AI new conversation screen
  },
});
```

</TabItem>
</Tabs>

- Use the string form for a simple setup.
- Use the object form to customize which index, credentials, or filters Ask AI uses.
- The suggested questions feature is controlled on the [Dashboard](https://dashboard.algolia.com) in the Ask AI section.

### Filtering search results

#### Keyword search

If your website uses [DocSearch meta tags][13] or if you've added [custom variables to your config][14], you'll be able to use the [`facetFilters`][16] option to scope your search results to a [`facet`][15]

This is useful to limit the scope of the search to one language or one version.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  searchParameters={{
    facetFilters: ['language:en', 'version:1.0.0'],
  }}
/>
```

</TabItem>

</Tabs>

#### Ask AI

Filtering also applies when using Ask AI. This is useful to limit the scope of the LLM's search to only relevant results.

:::info
We recommend using the `facetFilters` option when using Ask AI with multiple languages or any multi-faceted index.
:::

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">
```js
docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
```
</TabItem>

<TabItem value="react">
```jsx
<DocSearch
  askAi={{
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  }}
/>
```
</TabItem>

</Tabs>

:::tip
You can use `facetFilters: ['type:content']` to ensure Ask AI only uses records where the `type` attribute is `content` (i.e., only records that actually have content). This is useful if your index contains records for navigation, metadata, or other non-content types.
:::

### Sending events

You can send search events to your DocSearch index by passing in the `insights` parameter when creating your DocSearch instance.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```diff
docsearch({
   // other options
+  insights: true,
});
```

</TabItem>

<TabItem value="react">

```diff
<DocSearch
  // other options
+  insights={true}
/>
```

</TabItem>

</Tabs>

## Performance optimization

### Preconnect

Improve the loading speed of your initial search request by adding this snippet into your website's `<head>` section:

```html
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
```

This helps the browser establish a quick connection with Algolia, enhancing user experience, especially on mobile devices.

[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
[2]: https://github.com/algolia/docsearch/
[3]: https://github.com/algolia/docsearch/tree/master
[4]: /docs/legacy/dropdown
[5]: /docs/integrations
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[7]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[8]: https://codesandbox.io/s/docsearch-js-v3-playground-z9oxj
[9]: https://codesandbox.io/s/docsearch-react-v3-playground-619yg
[10]: https://www.npmjs.com/
[11]: /docs/api#container
[12]: /docs/api
[13]: /docs/required-configuration#introduce-global-information-as-meta-tags
[14]: /docs/record-extractor#indexing-content-for-faceting
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
[17]: /docs/composable-api
